💡 Motivation and Context

Ruby apps that send transactional email through PostHog can't copy anyone in or attach a file: client.emails.send from #324 takes one recipient and no files. An invoice, a receipt or a ticket export has to go out through another provider. posthog-node and posthog-python now take cc, bcc and attachments (PostHog/posthog-js#5514, PostHog/posthog-python#1172), and the send route accepts them (PostHog/posthog#127988). This PR adds the same three fields to posthog-ruby.

posthog.emails.send(
  to: 'user@example.com', template_key: 'invoice', subject: 'Your invoice', html: rendered_html,
  cc: 'billing@example.com', bcc: ['audit@example.com'],
  attachments: [
    { filename: 'invoice.pdf', content: File.binread('invoice.pdf') },
    { filename: 'logo.png', content: File.binread('logo.png'), content_type: 'image/png', content_id: 'logo' }
  ]
)

Stacked on #324; review that one first.

What it does

• cc and bcc: one address or a list, like reply_to. An empty list is left out of the request.
• attachments: a list of Hashes with filename, content, and optionally content_type and content_id. A content_id shows the file inline, referenced from the HTML as cid:<id>. Keys can be Symbols or Strings. An empty list is left out.
• Content: Ruby has one String type for text and bytes, so the client decides by encoding:
  • a binary String, as File.binread returns, is the file's bytes, and the client encodes it as Base64;
  • a list of byte values, as Resend's Ruby SDK takes (File.binread(path).bytes), is encoded the same way;
  • any other String must already be Base64. Base64 with line breaks is taken only in the exact layout Base64.encode64 writes, and sent without them; other text with line breaks is refused, so a text file read with File.read never goes out garbled. Text that isn't ASCII, such as a PDF read with File.read, can't be Base64 and is refused with a hint to use File.binread.
    Encoding happens once, before the first attempt, so retries send the same body.
• Refused before any request, with PostHog::EmailError code invalid_attachment, name validation_error, and a field such as attachments__0__content, as in Node and Python:
  • an attachment given by path (the client reads no files);
  • an unknown key, a missing filename or content, or text that isn't Base64 (including text that isn't ASCII).
    The message never holds the file's content.
• Refused by PostHog, as PostHog::EmailError invalid_request with the field and the server's message, why and fix: blocked file types, unsafe filenames or content IDs, more than 10 addresses per field or 10 files, and more than 512 KB decoded in total.
• The template form (template_id) refuses all three fields, as it does subject and html.

Impact

Pays into the Workflows team's growth goal for Messaging (email is in scope) through transactional email sends from server SDKs. It removes a reason a Ruby app keeps a second email provider: invoices, receipts and exports need attachments. Expected move: small, up, once released. Run cost: n/a, same send route. Measure: sends with attachments or copies by SDK, not measured yet; it needs the same User-Agent attribution as #324.

Merge Danger

Low, two-way door until release. The change is additive: the three keywords are new and optional, and a send without them builds the same request as before. Releasing the gem makes the shape public, so the content rule (binary String, byte list, or Base64 text) should settle in review. Releasing before the server deploys would make sends with these fields fail with the server naming the field.

💚 How did you test it?

• Lane gate on df3ff92: bundle exec rspec spec/posthog/emails_spec.rb 71 examples, three runs in random order, 0 failures; the full suite, 2090 examples, 0 failures. bundle exec rubocop: 146 files, no offenses. bundle exec rake public_api:check passes.
• CI on df3ff92: 20 checks green.
• Test seam: spec/posthog/emails_spec.rb, describe 'copies and attachments', drives Client.new(...).emails.send against WebMock at the HTTP boundary: the wire body for every content form, Symbol and String keys, empty lists left out, one Base64 encoding shared by every retry, each client-side refusal with its field, and the template form refusing the fields.
• Live send on df3ff92 through a local PostHog stack: Django at feat(messaging): send cc, bcc and attachments on a code send posthog#127988 (on #127123), cdp-api and the email and hogflow CDP workers at #127986 (on #127995 and #127985), the email flags on, and maildev as the SMTP server. A proxy between the Ruby client and Django records each request and response. Every case calls client.emails.send:
  1. to, two cc, one bcc, a PDF from File.binread and an inline PNG with content_id: 'logo': SendResult with an id. maildev holds one message, with to and both cc in the headers and the bcc address only in the envelope (no Bcc header). Both files arrive byte for byte (sha256), and the PNG is inline with Content-ID: <logo>, which the HTML's cid:logo uses.
  2. A byte list (File.binread(path).bytes) and an already-encoded Base64 string: delivered, both files byte for byte.
  3. An attachment given by path: PostHog::EmailError invalid_attachment, field attachments__0__path. No request reaches PostHog, and no mail arrives.
  4. An .exe: HTTP 400, EmailError invalid_request, field attachments__0__filename, "Mailbox providers block .exe files.", with the server's why and fix. No mail.
  5. Two files of 300 KB: HTTP 400, EmailError invalid_request, field attachments, "Send at most 512 KB of attachments in total, counted after decoding." No mail.
  6. Empty cc, bcc and attachments lists: the request body has none of the three keys, and the email is delivered.
• Cross-version on df3ff92: bodies from feat(emails): send transactional email and read its status #324's SDK and from this PR go through the real SendEmailSerializer of the server before these fields (213fad6, the base of feat(messaging): send cc, bcc and attachments on a code send posthog#127988) and after (#127988). feat(emails): send transactional email and read its status #324's sends are accepted by the new server. This PR's plain sends and sends with empty lists are accepted by the old server. A send with cc, bcc or attachments is refused there, naming the field, rather than going out without it.
• Contract test: the same six cases' request bodies also go through code_send_fields.py from #127988 on the Django and DRF versions the server pins. 15 of 15 checks pass.
• Gaps: none.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed. The YARD docs on Emails#send describe the three keywords.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file. posthog-ruby minor.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Built with Claude Code (Claude Opus 5.5) as one slice of a map that brings every server SDK to parity on emails.send. The shape follows posthog-node and posthog-python.

Involvement: no grilling rounds, no prototypes; QA swarm round 1 (nine lenses, including the team's michael and sdk-spec-conformance perspectives) and round 2 on the fixes, with fixes in a3a1aab and e29b8a7, then two clean final reads, the second on df3ff92; live send, cross-version and contract proofs captured.

🤖 Generated with Claude Code